Skip to main content

Hat Lab: Custom Option Images

Use product media alt text to set custom images for first-level variant options (e.g., Size) instead of using the first variant's image.

Setup​

  1. In the Theme Editor, go to the Hat Lab section settings
  2. Enable "Enable custom option images" under "Step 2: Select Color"
  3. Make sure a Collection is assigned to the Hat Lab section

Alt Text Pattern​

Add the option name and value to your image's alt text:

[OptionName]: [OptionValue]

Examples​

Basic usage:

Size: Classic - 57cm to 59cm

With descriptive alt text (recommended for accessibility):

Blue flat bill hat on white background Style: Flat Bill

Multiple option values for one image:

Line drawing of a baseball cap with perforated design on a white background
Size: Classic - 57cm to 59cm
Size: Small - 55cm to 58cm

How It Works​

  1. The system looks for "[OptionName]: " in the alt text (e.g., "Size: ")
  2. Extracts the value after the pattern
  3. Matches it to the option value using Shopify's handleize format
  4. If no custom image is found, falls back to the variant's featured image

Notes​

  • Only applies to the first option in the product (typically Size or Style)
  • Option values are matched using handleize (lowercase, hyphens instead of spaces)
  • The feature requires a collection to be set in the section settings
  • Multiple [OptionName]: [Value] entries can be on separate lines in the same alt text